ATSUSetLineControls

OSStatus ATSUSetLineControls (
                     ATSUTextLayout iTextLayout,
                     UniCharArrayOffset iLineStart,
                     ItemCount iAttributeCount,
                     ATSUAttributeTag iTag[],
                     ByteCount iValueSize[],
                     ATSUAttributeValuePtr iValue[]);

iTextLayout

A reference of type ATSUTextLayout. Pass a reference to a text layout object that contains the line whose attribute values you want to set. You cannot pass NULL for this parameter.

iLineStart

A value of type UniCharArrayOffset. Pass the edge offset of the beginning of the line whose attribute values you want to set.

iAttributeCount

The number of attributes you want to set for the line. This value should correspond to the number of elements in the iTag, iValueSize, and iValue arrays.

iTag

An array of values of type ATSUAttributeTag. Each element in the array must contain a valid tag that corresponds to a text layout attribute value in the line. See Text Layout Attribute Tag Constants for a description of Apple-defined tag values. If you pass a style run attribute or an ATSUI-reserved tag value in this parameter, ATSUSetLineControls returns the result code kATSUInvalidAttributeTagErr. You cannot pass NULL for this parameter.

iValueSize

An array of values of type ByteCount. Each element in the array must contain the size (in bytes) of the corresponding text layout attribute value being set. If you pass a size that is less than required, ATSUSetLineControls returns the result code kATSUInvalidAttributeSizeErr, and the function sets no attributes. If, after having checked all the given sizes and found them acceptable, ATSUSetLayoutControls sets text layout attributes. You cannot pass NULL for this parameter.

iValue

An array of pointers of type ATSUAttributeValuePtr. Each pointer in the array must reference a valid value and correspond to a tag in the iTag array. If you pass an invalid or undefined value, ATSUSetLineControls returns the result code kATSUInvalidAttributeValueErr. You cannot pass NULL for this parameter.

function result

A result code. See Result Codes. If there is a function error, ATSUSetAttributes will not set any style run attributes.

DISCUSSION

The ATSUSetLineControls function sets one or more text layout attribute value(s) for a single line in a text layout object. Note that when you set a text layout attribute value for a line, this value will override the value of the text layout attribute set for the text layout object containing the line. This is true even if the attributes for the line are set before those of the entire text layout object containing the line. If you wish to set the text layout attribute values for an entire text layout object, see the function ATSUSetLayoutControls.

ATSUI functions that operate on a line of text like ATSUDrawText, ATSUMeasureText, ATSUMeasureTextImage, and ATSUGetGlyphBounds, use text layout attributes that have been set by calling ATSUSetLineControls to calculate dimensions. If none have been set for the line, they use those set for the text layout object containing the line. If none have been set for the text layout object containing the line, ATSUI assigns them their default value. Default text layout attribute values are described in Table C-2.

SPECIAL CONSIDERATIONS

ATSUSetLineControls may allocate memory in your application heap, unless you designate a different heap by calling the function ATSUCreateMemorySetting.

VERSION NOTES

Available beginning with ATSUI 1.1.